// 定义包路径，属于驾校模块的web控制器
package com.ruoyi.web.controller.jiaxiao;

// 导入所需的Java工具类和Servlet相关类
import java.util.List;
import javax.servlet.http.HttpServletResponse;
// 导入Spring安全框架注解
import org.springframework.security.access.prepost.PreAuthorize;
// 导入Spring依赖注入相关注解
import org.springframework.beans.factory.annotation.Autowired;
// 导入Spring MVC相关注解
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
// 导入系统自定义的注解和类
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.enums.BusinessType;
import com.ruoyi.system.domain.JxExamRecord;
import com.ruoyi.system.service.IJxExamRecordService;
import com.ruoyi.common.utils.poi.ExcelUtil;
import com.ruoyi.common.core.page.TableDataInfo;

/**
 * 学员考试记录Controller
 *
 * @author ruoyi
 * @date 2025-01-27
 */
// 标识该类为REST风格的控制器
@RestController
// 定义请求路径前缀，所有该控制器的接口都以/jiaxiao/exam开头
@RequestMapping("/jiaxiao/exam")
// 继承基础控制器，获得一些通用功能
public class JxExamRecordController extends BaseController
{
    // 自动注入学员考试记录服务接口的实现类
    @Autowired
    private IJxExamRecordService jxExamRecordService;

    /**
     * 查询学员考试记录列表
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:list权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:list')")
    // 定义GET请求的接口路径
    @GetMapping("/list")
    // 处理查询学员考试记录列表的请求
    public TableDataInfo list(JxExamRecord jxExamRecord)
    {
        // 开始分页，从请求参数中获取分页信息
        startPage();
        // 调用服务层方法查询符合条件的学员考试记录列表
        List<JxExamRecord> list = jxExamRecordService.selectJxExamRecordList(jxExamRecord);
        // 将查询结果转换为表格数据格式并返回
        return getDataTable(list);
    }

    /**
     * 导出学员考试记录列表
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:export权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:export')")
    // 日志注解，记录操作标题和业务类型为导出
    @Log(title = "学员考试记录", businessType = BusinessType.EXPORT)
    // 定义POST请求的接口路径
    @PostMapping("/export")
    // 处理导出学员考试记录列表的请求
    public void export(HttpServletResponse response, JxExamRecord jxExamRecord)
    {
        // 调用服务层方法查询符合条件的学员考试记录列表
        List<JxExamRecord> list = jxExamRecordService.selectJxExamRecordList(jxExamRecord);
        // 创建Excel工具类实例，指定导出的数据类型
        ExcelUtil<JxExamRecord> util = new ExcelUtil<JxExamRecord>(JxExamRecord.class);
        // 调用工具类方法导出Excel文件
        util.exportExcel(response, list, "学员考试记录数据");
    }

    /**
     * 获取学员考试记录详细信息
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:query权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:query')")
    // 定义GET请求的接口路径，{examId}为路径参数
    @GetMapping(value = "/{examId}")
    // 根据考试ID查询学员考试记录详细信息
    public AjaxResult getInfo(@PathVariable("examId") Long examId)
    {
        // 调用服务层方法查询指定ID的考试记录，并封装成成功的AjaxResult返回
        return success(jxExamRecordService.selectJxExamRecordByExamId(examId));
    }

    /**
     * 新增学员考试记录
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:add权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:add')")
    // 日志注解，记录操作标题和业务类型为新增
    @Log(title = "学员考试记录", businessType = BusinessType.INSERT)
    // 定义POST请求的接口路径
    @PostMapping
    // 处理新增学员考试记录的请求
    public AjaxResult add(@RequestBody JxExamRecord jxExamRecord)
    {
        // 调用服务层方法插入数据，并将结果转换为AjaxResult返回
        return toAjax(jxExamRecordService.insertJxExamRecord(jxExamRecord));
    }

    /**
     * 登记考试记录（包含业务规则）
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:register权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:register')")
    // 日志注解，记录操作标题和业务类型为新增
    @Log(title = "登记考试记录", businessType = BusinessType.INSERT)
    // 定义POST请求的接口路径
    @PostMapping("/register")
    // 处理登记考试记录的请求（包含特定业务规则）
    public AjaxResult register(@RequestBody JxExamRecord jxExamRecord)
    {
        try {
            // 调用服务层方法登记考试记录，并将结果转换为AjaxResult返回
            return toAjax(jxExamRecordService.registerExamRecord(jxExamRecord));
        } catch (Exception e) {
            // 捕获异常并返回错误信息
            return error(e.getMessage());
        }
    }

    /**
     * 修改学员考试记录
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:edit权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:edit')")
    // 日志注解，记录操作标题和业务类型为更新
    @Log(title = "学员考试记录", businessType = BusinessType.UPDATE)
    // 定义PUT请求的接口路径
    @PutMapping
    // 处理修改学员考试记录的请求
    public AjaxResult edit(@RequestBody JxExamRecord jxExamRecord)
    {
        // 调用服务层方法更新数据，并将结果转换为AjaxResult返回
        return toAjax(jxExamRecordService.updateJxExamRecord(jxExamRecord));
    }

    /**
     * 删除学员考试记录
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:remove权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:remove')")
    // 日志注解，记录操作标题和业务类型为删除
    @Log(title = "学员考试记录", businessType = BusinessType.DELETE)
    // 定义DELETE请求的接口路径，{examIds}为路径参数，支持批量删除
    @DeleteMapping("/{examIds}")
    // 处理删除学员考试记录的请求
    public AjaxResult remove(@PathVariable Long[] examIds)
    {
        // 调用服务层方法批量删除数据，并将结果转换为AjaxResult返回
        return toAjax(jxExamRecordService.deleteJxExamRecordByExamIds(examIds));
    }

    /**
     * 查询学员某科目的考试记录
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:query权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:query')")
    // 定义GET请求的接口路径，{studentId}和{subjectId}为路径参数
    @GetMapping("/student/{studentId}/subject/{subjectId}")
    // 根据学员ID和科目ID查询考试记录
    public AjaxResult getExamRecordsByStudentAndSubject(@PathVariable("studentId") Long studentId,
                                                        @PathVariable("subjectId") Long subjectId)
    {
        // 调用服务层方法查询指定学员和科目的考试记录
        List<JxExamRecord> list = jxExamRecordService.selectJxExamRecordByStudentAndSubject(studentId, subjectId);
        // 将查询结果封装成成功的AjaxResult返回
        return success(list);
    }

    /**
     * 查询学员所有科目的考试记录
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:query权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:query')")
    // 定义GET请求的接口路径，{studentId}为路径参数
    @GetMapping("/student/{studentId}")
    // 根据学员ID查询所有科目的考试记录
    public AjaxResult getExamRecordsByStudent(@PathVariable("studentId") Long studentId)
    {
        // 调用服务层方法查询指定学员的所有考试记录
        List<JxExamRecord> list = jxExamRecordService.selectJxExamRecordByStudent(studentId);
        // 将查询结果封装成成功的AjaxResult返回
        return success(list);
    }

    /**
     * 检查学员是否可以参加某科目考试
     */
    // 方法级别权限控制，只有拥有jiaxiao:exam:query权限的用户才能访问
    @PreAuthorize("@ss.hasPermi('jiaxiao:exam:query')")
    // 定义GET请求的接口路径，{studentId}和{subjectId}为路径参数
    @GetMapping("/canTake/{studentId}/{subjectId}")
    // 检查学员是否可以参加某科目考试
    public AjaxResult canTakeExam(@PathVariable("studentId") Long studentId,
                                  @PathVariable("subjectId") Long subjectId)
    {
        // 调用服务层方法检查学员是否可以参加指定科目考试
        boolean canTake = jxExamRecordService.canTakeExam(studentId, subjectId);
        // 将检查结果封装成成功的AjaxResult返回
        return success(canTake);
    }
}